gh-123452: Improved ToC navigation within documentation sections #123453
Conversation
|
All commit authors signed the Contributor License Agreement. |
|
Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool. If this change has little impact on Python users, wait for a maintainer to apply the |
|
Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool. If this change has little impact on Python users, wait for a maintainer to apply the |
|
I don't believe this needs a NEWS entry since it's a docs change, but lmk if it needs one and i'll write it |
|
I really like the results and the code looks clean and tight (didn't build the docs locally). Has this been discussed on discuss.python.org already? If not, that could be a way to attract reviews from core docs people. If it has been discussed, I can try pinging some people that would be interested in joining the discussion. |
Do the preview docs get the gist? though that build is outdated at this point: https://cpython-previews--123453.org.readthedocs.build/
No, I had not posted it there! Is that a standard part of the contributing process? Sorry if I missed that. I'll post there when I'm back at home at keyboard. Edit: sorry for causing noise, just saw rebasing re-requested review. |
sneakers-the-rat
force-pushed
the
docs-toc
branch
from
6a639fc to
38baf4a
Compare
No, but it can be an interesting way of getting feedback and attention. No pressure or hurry to post, just a suggestion if you feel like it :) |
3 participants
fix: #123452
This PR makes two minor modifications:
Global ToC
Currently
this is roughly 1/20th of the total Toc length. The changelog/whats new go on for about half of that, and the user-facing tutorial and language reference is >halfway down.
expand/collapse long image
This PR
expand/collapse long image
Local ToC
Currently
The current sub-document/document section is not shown, and the "Table of Contents" links to the global ToC
This PR
Within-Document ToC
The current sub-document/document section is linked at the top of the table of contents when any such parents exist. There aren't any double-nested documents as far as i can tell, but if there were, then they would be be shown with successive header levels.
Index ToC
When there is no parent, as is the case in the section ToC's, a link to the global ToC is shown.
Discussion
Unlike sphinx's localtoc, the toc is always shown even when it only has one link in it, as that is how the title of individual pages/ToCs is encoded - without it, sometimes the "Table of Contents" link is absent and sometimes it's not, and it's unclear without understanding the code why that would be.
I am hoping this is a relatively uncontroversial PR, as it is a small change to the code that would make a relatively large improvement to the usability of the docs for those of us who read on mobile or split their screen into columns where the breadcrumbs are invisible. I tried to follow naming conventions for
customlocaltoc.htmlmimickingcustomsourcelink.html, but am happy to modify this however the maintainers would like :)📚 Documentation preview 📚: https://cpython-previews--123453.org.readthedocs.build/